Skip to content

doc: Modernize documentation, platforms, algorithms, architecture, and binary releases - #522

Merged
lgirdwood merged 23 commits into
thesofproject:masterfrom
lgirdwood:topic/docs-modernization
Sep 13, 2026
Merged

doc: Modernize documentation, platforms, algorithms, architecture, and binary releases#522
lgirdwood merged 23 commits into
thesofproject:masterfrom
lgirdwood:topic/docs-modernization

Conversation

@lgirdwood

Copy link
Copy Markdown
Member

What

Comprehensive modernization of the SOF technical documentation:

  1. Single Source of Truth (SSOT) Data Architecture:
    • Introduced YAML databases in data/ (platforms.yaml, legacy_platforms.yaml, modules.yaml, sof_bin_releases.json).
    • Automated RST generation script (scripts/generate_matrices.py) integrated into make html.
  2. Supported & Legacy Platforms Matrices (1 SoC Per Row):
    • Disaggregated platforms so every silicon target has its own row across both supported and legacy tables.
    • Added 1st column for Vendor brand icons (Intel, AMD, NXP, MediaTek, PJRC, Espressif, QEMU).
    • Added modern targets: Arrow Lake (ARL/ARL-S), Panther Lake (PTL), Wildcat Lake (WCL), Nova Lake (NVL/NVL-S), Teensy 4.1 (ARM Cortex-M7), and ESP32-P4 audio bridges.
  3. Audio Algorithms & Processing Modules Catalog:
    • Disaggregated algorithms to 1 algorithm per row (33 distinct modules).
    • Added Source column (SOF, FFmpeg, WebRTC, Steam Audio, Google).
    • Added SIMD column detailing DSP instruction set flavors (ARM, RISCV, HiFi 2 EP, HiFi 3, HiFi 4, HiFi 5, VFPU, Scalar C).
    • Added Status column distinguishing Upstream from Active Development.
  4. Architecture & Developer Guides Reorganization:
    • Streamlined top-level Architecture page to high-level system models, hostless embedded architectures (with Bluetooth A2DP/HFP/LC3/Auracast), and pipeline DAGs.
    • Relocated platform-specific architectures and subsystem guides to developer_guides/.
    • Relocated algorithm tuning and implementation guides to developer_guides/algorithms/.
  5. Firmware Binary Releases:
    • Overhauled release.rst to focus solely on sof-bin pre-built binary distributions.
    • Dynamically fetches release metadata from GitHub API at build time with offline JSON caching fallback.
    • Embedded client-side live GitHub status badge.
  6. Theme & Styling Modernization:
    • Modernized styling with PyData Sphinx theme support, adaptive dark/light SVG favicon, dark-mode tabs, and responsive layout widening.
    • Updated copyright to 2026.

Verification

  • make html LAX=1 builds with 0 errors and 0 warnings.
  • Verified all internal cross-references, images, and tables render cleanly.
  • Tested offline build resilience using local JSON cache.
  • Verified live rendering locally via Sphinx preview server.

All patches include Signed-off-by: Liam Girdwood liam.r.girdwood@linux.intel.com.

…ges deployment

- Modernize introduction page with project mission, licensing, and
  detailed explanation of audio DSP offloading benefits (power, latency,
  vertical audio stack, CPU compute offload).
- Replace legacy raster images with four scalable vector Graphviz diagrams:
  * Host-based system and software architecture (Android, ChromeOS, Linux).
  * Hostless standalone embedded architecture (Zephyr RTOS, ESP32-P4,
    Teensy 4.1) including Bluetooth audio endpoints (A2DP, HFP, LE Audio,
    Auracast) and BT HCI HAL drivers.
  * Audio processing pipeline DAG with ALSA control bindings.
  * Symmetrically aligned SDK tooling and development workflow.
- Introduce single source of truth (SSOT) YAML databases for platforms
  and audio processing modules in data/, with automated table generation
  via scripts/generate_matrices.py.
- Update platform matrix to include Teensy 4.1 (ARM Cortex-M7), Arrow
  Lake (ARL), Panther Lake (PTL), and ESP32-P4 audio bridges.
- Update algorithms catalog to include AAC/MP3 VFPU, Valve Steam Audio
  binaural spatializer, AEC, and microphone beamforming.
- Add GitHub Pages deployment workflow (.github/workflows/deploy.yml)
  using native GitHub Pages actions with OIDC permissions.
- Support PyData Sphinx theme with fallback, MyST markdown parser, and
  Makefile automated data generation.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
- Move full system & software architecture, hostless architecture (with
  Bluetooth A2DP/HFP/LC3/Auracast endpoints), pipeline DAG, firmware
  subsystems, and topology architecture to architectures/index.rst.
- Move SDK development workflow diagram and core SDK ingredients to
  getting_started/index.rst with balanced 3-column layout.
- Add cross-references to main architecture hub from firmware and host index pages.
- Streamline introduction/index.rst with sof-waveform artwork, move Project
  Mission above offload benefits, and link out to dedicated hubs.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
- Extract FAQ into dedicated top-level portal (faq/index.rst)
- Update architecture index with Zephyr RTOS foundation and relocate memory hierarchy
- Rewrite Getting Started Build SOF section from scratch using sdk-install.sh
- Add OS tabs for Ubuntu/Debian and Fedora/RHEL system dependencies
- Add sphinx-copybutton extension for one-click command copying
- Remove legacy getting_started/build-guide subpages and update cross-references
- Update requirements.txt and requirements-lax.txt with modern documentation dependencies

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…rk mode

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…structions

- Mark Zephyr SDK toolchain as mandatory (Step 3).
- Update open-source Xtensa compiler instructions to use lgirdwood/llvm-project fork (llvm-stable branch) with compiler-rt builtins and WIP branches.
- Remove Step 7 (LLEXT build) from the main getting started page.
- Move kernel build environment setup directly into getting_started/index.rst while preserving the prepare-build-environment anchor.
- Update cross-references in install_locally.rst and setup_ktest_environment.rst.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…er guides

- Rename firmware build section to 'Build and Install SOF Firmware'.
- Remove intermediate 'Set up SOF on a Linux machine' section.
- Create unified 'Build and Install SOF Linux Drivers' section integrating local kernel build, configuration, compilation, local install, verification, rebuild, and removal instructions directly.
- Move the 4 specialized platform/debug sections (special devices, Intel debug, NXP, LMDK) from getting started to developer guides.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
- Relocate setup_ktest_environment.rst to developer_guides/ktest/.
- Add 'Remote Deployment with ktest' section to developer_guides/index.rst.
- Replace ktest toctree in getting_started/index.rst with an inline note linking to the developer guide.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…feedback

- Add high-level firmware architecture Graphviz diagram partitioned into
  SOF Application Layer (modules, schedulers, IPC, memory, endpoints)
  and Zephyr RTOS Layer (HAL drivers, kernel core, timers, logging, PM).
- Update architecture intro phrasing from 'is architected' to 'is designed'.
- Remove personal name from Xtensa LLVM/Clang development fork reference.
- Add concluding 'Next Steps' section linking to architectures, algorithms,
  developer guides, and platform matrix.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…icon

- Vertically align SOF Application Layer and Zephyr RTOS Layer clusters
  in the high-level firmware architecture diagram so that outer boundaries
  and internal columns are balanced with straight-down inter-layer arrows.
- Replace low-contrast favicon with an adaptive SVG favicon supporting
  CSS @media (prefers-color-scheme: dark), switching between crisp white
  bars on dark browser tabs and navy bars on light browser tabs.
- Add dynamic theme observer in static/sof-custom.js to sync favicon
  with documentation theme toggle.
- Provide high-contrast PNG fallbacks with crisp white outline for 16x16
  and 32x32 resolutions.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…pology sections

- Add Vendor column to supported platforms table with brand icons (Intel, AMD, NXP, MediaTek, PJRC / NXP, Espressif, Emulation).
- Slim primary navigation sidebar (13.5%, max 210px) and secondary TOC sidebar (11.5rem) to maximize central content reading width.
- Remove redundant Zephyr RTOS Foundation section from architecture overview.
- Relocate Audio Processing Pipelines (DAGs) under What is an SOF Topology? in Audio Topology Architecture.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
- Split shared platform rows in data/platforms.yaml so that each SoC has its own row (including Alder Lake variants, Raptor Lake variants, Arrow Lake variants, AMD Rembrandt/Phoenix/Strix, NXP i.MX8/i.MX9, and MediaTek MT8195/MT8186/MT8188/MT8196).
- Create data/legacy_platforms.yaml for platforms no longer supported in mainline, ensuring 1 SoC per row (Bay Trail, Merrifield, Cherry Trail, Braswell, Broadwell, Apollo Lake, Gemini Lake, Cannon Lake, Whiskey Lake, Comet Lake, Sue Creek, Ice Lake, Jasper Lake, Tiger Lake IPC3, Alder Lake IPC3).
- Update scripts/generate_matrices.py to generate both _generated_platforms_table.rst and _generated_legacy_platforms_table.rst with vendor icons in the 1st column.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…to Active Integration

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…c info to developer guides

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…veloper guides

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
… flavours

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
- Add 'Status' column to the algorithms and processing modules table
  distinguishing 'Upstream' mainline modules from 'Active Development'
  integrations (FFmpeg LLEXT, WebRTC, Steam Audio, TFLite Micro).
- Integrate ARM SIMD (Cortex-M7 DSP intrinsics from Teensy 4.1 PR) and
  RISC-V SIMD (ESP32-P4 PR) into supported SIMD flavors for accelerated
  modules (Volume, Mixer, SRC, ASRC, EQ FIR, EQ IIR, DRC, Multiband DRC,
  Crossover, DC Blocker, TDFB, Tone).

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
- In data/modules.yaml, rename 'ARM SIMD' to 'ARM' and 'RISC-V SIMD' to 'RISCV'
  for clean, concise SIMD flavor naming.
- In conf.py, update project copyright statement to '2026, SOF Project'.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
- Relocate algorithm implementation and tuning guides (demux, eq, src, tdfb)
  from algos/ to developer_guides/algorithms/.
- Add 'Algorithm Specific Information' section and toctree to developer_guides/index.rst.
- In algos/index.rst, replace the toctree with an informative cross-reference note,
  leaving the Algorithms page focused strictly on the algorithms catalog and SIMD matrix.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
- Dynamically fetch and display latest releases from thesofproject/sof-bin
  via GitHub API at build time with local JSON caching and client-side live check.
- Remove obsolete source and Linux driver git clone sections.
- Add binary release contents overview, target /lib/firmware layout, and installation guide.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
…CI workflows

- Update woke_pr.yml permissions and use github-pr-check reporter to prevent 403 API errors on PRs.
- Modernize hardware interface and bus naming (Controller/Target, Manager/Device, Peripherals) in architectures/index.rst and data/platforms.yaml to resolve woke linter violations.
- Update .wokeignore with relocated documentation paths.
- Add in-tree clone and build directories (sof, _deps, _build_doxy) to Sphinx exclude_patterns in conf.py so external firmware Markdown files are not scanned.
- Update scripts/constraints.txt lockfile with modern documentation dependencies.
- Remove redundant pull_request trigger from deploy.yml and add --depth 1 to SOF git checkouts in pull-request.yml.

Signed-off-by: Liam Girdwood <liam.r.girdwood@linux.intel.com>
@lgirdwood
lgirdwood merged commit dc24c5b into thesofproject:master Sep 13, 2026
5 checks passed
@lgirdwood
lgirdwood deleted the topic/docs-modernization branch September 13, 2026 18:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants